/* **********************************************************
 * Copyright (c) 2025 Google, Inc.  All rights reserved.
 * **********************************************************/

/*
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 *
 * * Neither the name of Google, Inc. nor the names of its contributors may be
 *   used to endorse or promote products derived from this software without
 *   specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */

#ifndef _NOISE_GENERATOR_H_
#define _NOISE_GENERATOR_H_ 1

#include "reader.h"
#include "scheduler.h"
#include "trace_entry.h"

namespace dynamorio {
namespace drmemtrace {

/**
 * Contains metadata information to drive the noise generation.
 */
struct noise_generator_info_t {
    noise_generator_info_t() = default;
    noise_generator_info_t(addr_t pid, addr_t tid, uint64_t num_records_to_generate)
        : pid(pid)
        , tid(tid)
        , num_records_to_generate(num_records_to_generate)
    {
    }
    // TODO i#7216: temporary default values.
    memref_pid_t pid = 1;
    memref_tid_t tid = 1;
    // TODO i#7216: this parameter drives the noise generation. Currently we only set a
    // default value of numbers of records to generate, but we plan to have more
    // parameters to control the mix of noise (e.g., load/store mix, address patterns with
    // strides). This is not the final set of parameters, we'll add them as needed
    // depending on the patter of noise we want to generate.
    uint64_t num_records_to_generate = 1000;
};

/**
 * Generates synthetic #dynamorio::drmemtrace::memref_t trace records in a single-process
 * single-thread and presents them via an iterator interface to the scheduler.
 * These synthetic trace records are preceded by TRACE_TYPE_THREAD, TRACE_TYPE_PID,
 * TRACE_MARKER_TYPE_TIMESTAMP records and followed by TRACE_TYPE_THREAD_EXIT, as this is
 * the order of records that the scheduler expects. The value of
 * TRACE_MARKER_TYPE_TIMESTAMP is (ULONG_MAX - 1), which is not a
 * serial-or-interval-suited timestamp value for mixing with real workload inputs.
 * A serial analysis combined with real workload inputs would have these synthetic
 * records at the very end, while time interval analysis would not consider these records
 * unless the interval is very large (likely beyond the end of real input workloads).
 * Noise generation is suited for dynamic scheduling, where the scheduler will re-write
 * the values of TRACE_MARKER_TYPE_TIMESTAMP.
 * Note that this class does not support simultaneous use by concurrent threads.
 */
class noise_generator_t : public reader_t {
public:
    noise_generator_t() = default;

    explicit noise_generator_t(noise_generator_info_t &info);

    virtual ~noise_generator_t() = default;

    bool
    init() override;

    std::string
    get_stream_name() const override;

protected:
    // Makes sure the noise records generated by generate_trace_entry() are preceded by
    // TRACE_TYPE_THREAD, TRACE_TYPE_PID, TRACE_MARKER_TYPE_TIMESTAMP and followed by
    // TRACE_TYPE_THREAD_EXIT.
    virtual trace_entry_t *
    read_next_entry() override;

    // Contains the main logic to generate noise records.
    virtual trace_entry_t
    generate_trace_entry();

    noise_generator_info_t info_ = {};

private:
    trace_entry_t entry_ = {};
    bool pid_generated_ = false;
    bool tid_generated_ = false;
    bool marker_timestamp_generated_ = false;
    // This counter does not count TRACE_TYPE_THREAD, TRACE_TYPE_PID, and
    // TRACE_MARKER_TYPE_TIMESTAMP. The idea is that when the user wants to generate at
    // at least one record, tid, pid, and timestamp always have to be there, otherwise
    // the scheduler will report an error. So, for example, if the user wants to generate
    // only one record, we cannot generate TRACE_TYPE_THREAD only.
    uint64_t num_records_generated_ = 0;
};

/**
 * Factory to create noise_generator_t.
 */
template <typename RecordType, typename ReaderType> class noise_generator_factory_t {
public:
    virtual ~noise_generator_factory_t() = default;

    std::string
    get_error_string();

    typename scheduler_tmpl_t<RecordType, ReaderType>::input_reader_t
    create_noise_generator(noise_generator_info_t &info);

protected:
    virtual std::unique_ptr<ReaderType>
    create_noise_generator_begin(noise_generator_info_t &info);

    virtual std::unique_ptr<ReaderType>
    create_noise_generator_end();

    std::string error_string_;
};

} // namespace drmemtrace
} // namespace dynamorio

#endif /* _NOISE_GENERATOR_H_ */
